Hello ~ 大家好，經過了前面幾天的練習後，是不是可以慢慢開發出API了呢 ?

那如果我們API愈來愈多，或是後端團隊要提供給前端團隊API文件，又或著是要跟其他跨單位合作的話，我們除了自己撰寫API文件，還有沒有其他更好的方式呢 ?!

這時候真的是讚嘆Swagger的發明，真的是後端人員的福音
所以我們接著就要來介紹甚麼是Swagger，跟我們如何應用她來快速生成文件了 ~~~

Swagger和OpenAPI

如官網文件所說，Swagger 是一套功能強大且易於使用的 API 開發工具，適用於團隊和個人，支援從設計和文件到測試和部署的整個 API 生命週期的開發。
而它的歷史，Swagger 是一間名為SmartBear Software 的公司，開發出的REST API 的工具，可以幫助設計、構建、記錄和使用REST API，後來貢獻給OpenAPI Initiative，並公開讓所有人都能夠使用。

Spring boot 如何使用Swagger/OpenAPI

因為我們已經使用Spring boot3.3.0的版本，所以建議搭配以下版本來使用，
在pom.xml加入以下dependency

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

接著我們可以設定application.properties ，也可以維持原本預設值

# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs
# 自訂義swagger-ui網址
springdoc.swagger-ui.path=

其他各詳細的部分，我們可以參考官網設定喔!

那如果甚麼設定都不改的話，我們可以直接在dependency加入後，啟動Application，輸入
http://localhost:8080/swagger-ui/index.html 就可以看到自動生成的API文件的UI介面👇

如果甚麼都沒有設定的話，也許會少了一些描述，所以我們接著再來介紹幾個常用的Annotation，讓我們生成的文件更加完整吧 ~

常見的Annotation

@Tag : 可以針對Controller命名跟描述

• 範例: 可以看到可以給予名稱和描述

@Tag(name = "IronMan Demo Service",description = "provide to demo bookStore service")

@Operation : 用來描述單一的URL

• 範例 : 可以針對該API定義命稱與描

@Operation(summary = "Gets book by ID", description= "Book must exist")

@ApiResponses & @ApiResponse : 可以針對API回傳的結果和http status code進行說明

• 範例

    @ApiResponses(value = {
            @ApiResponse(responseCode = "20", description = "Success to find book"),
            @ApiResponse(responseCode = "404", description = "Book not found")})

接著我們再重新看一次剛剛我們有多加說明的API在Swagger的樣貌吧~

是不是變得更完整呢 ?!
未來就可以寫完程式也就一起連同API文件一起完成了

參考文件

• Swagger官方文件
• springdoc-openapi官網